fix(mcp): emit search results once instead of content + structuredContent - #14175

Fixes #14171

Problem

search_indexed_documents is annotated -> dict[str, Any], so FastMCP derives an output schema from the annotation and sends the payload twice — once as structuredContent, and again as serialised JSON in a text content block. Every search result crosses the wire in duplicate.

For most tools that is cheap. For a search tool the payload is the retrieved document content, so the duplicate scales with everything retrieved.

Measurement

On fastmcp==3.2.0 (the pinned version), with a single-document payload:

In a self-hosted deployment with an agent client that forwards tool results to the model without capping, this was worth roughly 2.4k input tokens per search — about half the tool-result injection. Full standalone reproduction in #14171.

Why this is safe

• The content text is byte-identical — same pydantic_core.to_json of the same dict — so anything parsing the text path sees no change.
• The derived schema comes from dict[str, Any], which describes no structure, so clients gain nothing from the structured copy for this tool.
• search_web and open_urls are deliberately left as-is. They dual-emit too, but their payloads are small enough not to matter, and _error_payload stays a plain dict since open_urls shares it.

Note

output_schema=None on the decorator does not fix this — it drops the declared outputSchema from tools/list but the result still carries both representations. Verified on 3.2.0. An explicit ToolResult is what suppresses the duplicate.

Caveat

Dual emission is the spec-compliant default when a tool declares an output schema, so a client genuinely consuming the structured path for this tool would be affected. If you would rather have this behind a flag than as a change of default, I am happy to rework it — or to close this in favour of an approach you prefer.

Checks

• ruff format clean (0.16.0, per .pre-commit-config.yaml)
• ruff check reports no new findings — identical counts before and after
• Variant has been running in production for about a month

Summary by cubic

Emit search_indexed_documents results once by returning a ToolResult instead of a bare dict, removing the duplicate structuredContent. This halves the wire size on typical payloads and reduces token usage without changing the content text.

• Old vs new: previously fastmcp derived a schema from dict[str, Any] and sent both structuredContent and text; now only text content is sent.
• The text payload is byte-identical to before; parsers of the text path see no change.
• search_web and open_urls are unchanged.
• Migration: if any client consumes structuredContent for search_indexed_documents, switch to parsing the content text.

^{Written for commit 2ae57d2. Summary will update on new commits.}